Day 3 - 使用說明系統

16th鐵人賽

kanglin

2024-09-17 23:24:13

120 瀏覽

分享至

在本書第三章直截了當的講述了說明系統（ help system ）的重要性。

如果你不打算花時間閱讀 PowerShell 的說明文件，那麼你使用 PowerShell 的效果將大打折扣。你學不會如何使用它；你也學不會如何利用它來管理 Azure、AWS、Microsoft 365 等服務；那麼你還是繼續使用GUI會比較好。

看到這，讓我想到手把手帶我進維運的師傅在我第一年碰網路設備時，時常叮嚀著我，你不知道指令要怎麼完成時，你有嘗試執行 help 嗎？有在不知道要怎麼查詢或不知道有哪些參數可以帶時在指令的後方下過 ? 嗎，有時候道理就在那裡，大家都懂，但是做不做、看不看又是另一件事了，因此能透過指令介面的提示去延伸，這真的是個好習慣呢！

可更新的說明文件

當第一次透過指令 help 去查詢某個命令的說明時，會得到一個自動產生的精簡版內容，同時附帶一條如何更新說明文件的訊息。

精簡版截圖

透過指令更新 PowerShell 的說明文件

在 en-us 語言環境底下執行

Update-Help

如果不是在 en-us 語言環境底下執行的話，需要指定 UICulture en-US

Update-Help -UICulture en-US

查詢說明文件

當在 mac 或 Linux 上查看說明文件時，它們會透過作業系統中傳統的 man ( Unix/Linux 系統中用來查看命令說明文件的工具 ) 功能來呈現，它會暫時『佔用』整個畫面來顯示說明文件，當閱讀完畢後，視窗會回到正常的畫面。
本書中針對 help 的說明

PowerShell 提供了一個名為 Get-Help 的 cmdlet，用來存取說明系統。你可能會在一些範例（特別是網路上的範例）看到有人使用 Help 關鍵字來替代。但事實上，Help 關鍵字不是一個原生的 cmdlet；它是一個函式（ function ），它其實是 Get-Help 這個核心 cmdlet 的一個封裝。

一次看到所有說明文件

> Get-Help Get-Content

用分頁的方式進行瀏覽

> help Get-Content

說明系統兩大主要目標

一、協助找到能完成特定工作的命令。

使用 Help 尋找命令

參考 Microsoft Get-Help 文件並實作後，挑出幾個覺得日後用的到的作為筆記並結束這回合。

使用參數顯示 Cmdlet 的選取部分
這些範例會顯示 Cmdlet 說明的 Format-Table 選取部分。

Get-Help Format-Table -Examples
Get-Help Format-Table -Parameter *
Get-Help Format-Table -Parameter GroupBy

顯示概念性文章的清單
此範例會顯示 PowerShell 說明中包含的概念性文章清單。所有這些文章都是以字元 about_ 開頭。
```
Get-Help about_*
```
在 Cmdlet 說明中搜尋單字
此範例示範如何在 Cmdlet 說明文章中搜尋單字。
```
Get-Help Add-Member -Full | Out-String -Stream | Select-String -Pattern Clixml
```
Get-Help 會使用 Full 參數來取得的說明 Add-Member 資訊。 MamlCommandHelpInfo 物件會在管線下傳送。 Out-String會使用 Stream 參數將對象轉換成字串。 Select-String會使用 Pattern 參數來搜尋 Clixml 的字串。

二、找到那些命令後，教你正確的使用它們。

本書在 3.5 解析說明文件小章節中這樣說：

PowerShell 的 cmdlet 說明文件遵循一定的慣例。學會理解你所看到的內容，是從這些文件中獲取最多資訊，且更有效地使用 cmdlet 的重點關鍵。

多個參數集

並利用 Get-Item 的說明文件解釋當在 SYNTAX 區塊裡 Get-Item 被列出了兩次，表示 Get-Item 有兩種不同的使用方式（兩個參數集），但是你無法將兩個 Syntax 的參數集裡的參數全部套進去同一個 Get-Item 裡。

SYNTAX
    Get-Item [-CodeSigningCert] [-Credential <System.Management.Automation.PSCredential>] [-DnsName <Microsoft.PowerShell.Commands.DnsNameRepresentation>] [-DocumentEncryptionCert] [-Eku <System.String>] [-Exclude <System.String[]>] [-ExpiringInDays <System.Int32>] [-Filter <System.String>] [-Force] [-Include <System.String[]>] -LiteralPath <System.String[]> [-SSLServerAuthentication] [-Stream <System.String[]>] [<CommonParameters>]

    Get-Item [-Path] <System.String[]> [-CodeSigningCert] [-Credential <System.Management.Automation.PSCredential>] [-DnsName <Microsoft.PowerShell.Commands.DnsNameRepresentation>] [-DocumentEncryptionCert] [-Eku <System.String>] [-Exclude <System.String[]>] [-ExpiringInDays <System.Int32>] [-Filter <System.String>] [-Force] [-Include <System.String[]>] [-SSLServerAuthentication] [-Stream <System.String[]>] [<CommonParameters>]

選擇性參數和必要參數

在執行 cmdlet 時，不需要帶上所有的參數，在說明文件裡的參數集裡，會將選擇性參數（ optional parameter ）放在中括號中，通常參數的名稱及值如果同時被中括號包起來，那該參數就是選擇性參數，但是我更建議在使用參數前，先透過 help system 確認參數是否為必要參數。

get-help Get-Item -Parameter * | more

-CodeSigningCert <System.Management.Automation.SwitchParameter>
    This is a dynamic parameter made available by the Certificate provider. This parameter and the Certificate provider are only available on Windows.

    To get certificates that have `Code Signing` in their EnhancedKeyUsageList property value, use the CodeSigningCert parameter.

    For more information, see about_Certificate_Provider (../Microsoft.PowerShell.Security/About/about_Certificate_Provider.md).

    Required?                    false
    Position?                    named
    Default value                False
    Accept pipeline input?       False
    Accept wildcard characters?  false